package com.hnchances.studentscoresystem.service;

import com.github.pagehelper.PageInfo;
import com.hnchances.studentscoresystem.dto.request.GradesDeleteDTO;
import com.hnchances.studentscoresystem.dto.request.GradesQueryDTO;
import com.hnchances.studentscoresystem.dto.request.GradesUpdateDTO;
import com.hnchances.studentscoresystem.dto.response.GradesPageResponse;
import com.hnchances.studentscoresystem.dto.response.GradesQueryResponse;
import com.hnchances.studentscoresystem.dto.response.GradesOperateResponse;
import com.hnchances.studentscoresystem.entity.Grades;

/**
 * 成绩管理 Service 接口（核心业务）
 * 对应数据库表：grades
 * 核心需求：成绩增删改查（老师权限控制、多条件查询、分页）
 */
public interface GradesService extends BaseService<Grades, Long> {

    /**
     * 新增成绩（鉴权：仅老师可登记本班级成绩）
     * @param grades 成绩实体（含班级ID、学生ID等关联信息）
     * @param operatorId 操作人 ID（老师）
     * @param operatorClassId 操作人班级 ID（校验权限）
     * @return 操作结果（含成绩 ID）
     */
    GradesOperateResponse addGrades(Grades grades, Long operatorId, Integer operatorClassId);

    /**
     * 多条件查询成绩（鉴权：老师仅查本班级成绩，支持分页）
     * @param queryDTO 查询条件（学生姓名/班级/课程/考试）
     * @param operatorIdentity 操作人身份（0-学生，1-老师，2-管理员）
     * @param operatorClassId 操作人班级 ID（老师需匹配）
     * @return 分页成绩列表
     */
    GradesPageResponse queryGrades(GradesQueryDTO queryDTO, Integer operatorIdentity, Integer operatorClassId);

    /**
     * 更新成绩（鉴权：仅老师可修改本班级成绩）
     * @param updateDTO 修改条件（含成绩 ID、新分数等）
     * @param operatorId 操作人 ID（老师）
     * @param operatorClassId 操作人班级 ID（校验权限）
     * @return 操作结果
     */
    GradesOperateResponse updateGrades(GradesUpdateDTO updateDTO, Long operatorId, Integer operatorClassId);

    /**
     * 软删除成绩（鉴权：仅老师可删除本班级成绩）
     * @param deleteDTO 删除条件（含成绩 ID）
     * @param operatorIdentity 操作人身份（0-学生，1-老师，2-管理员）
     * @param operatorClassId 操作人班级 ID（老师需匹配）
     * @return 操作结果
     */
    GradesOperateResponse deleteGrades(GradesDeleteDTO deleteDTO, Integer operatorIdentity, Integer operatorClassId);
}